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1. Introduction 


P?L0T ? J 603 the i "’P^"'entation details of the Atari 

s3s?L terpreter £or the Atari Personal Computer 

System. The Atari PILOT language is described in a L 

manual entitled 'ATARI PILOT EXTERNAL SPECIFICATION'. 


The PILOT interpreter resides in an 
all of the available RAM memory for 
memory requirements. Static memory 


8K byte cartridge and uses 
its own static and dynamic 
requirements include: 


I ® ^ pr e t e r working variables. 

Mode control and option flags. 

Numeric variable storage. 

Numeric expression stack. 

Use stack. 

Accept, text expression and command line buffers. 


Dynamic memory requirements include: 


Program statement storage. 
String variable storage. 

Gr aph i c s/ t ex t screen area. 


The interpreter utilizes the Screen 
command lines, which may be immediat 
statements or line deletions; thus, 
provided before the interpreter sees 


Editor as a source for 
e commands, deferred PILOT 
full line editing is 
the input line. 


The interpreter 
operations; the 
transformed in a 
to integer form 


utilizes PILOT 
statements are 
ny way, except 
for internal p 


source statement 
never tokenized, 
that line number 
rogram storage. 


s 

s 


for all 
compiled 
are conv 


or 

er ted 


\ 
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2. Interpreter operation 

The interpreter is at all times reading PILOT statements, but 
depending upon the operating mode different actions are taken. 

The primary operating modes and their behaviors are: 

Immediate mode -- PILOT statements are read from the Screen 
Editor and result in either immediate execution, a storage to 
the program storage area or a statement deletion. 

Run mode -- PILOT statements are read from the program storage 
area and executed. 

Auto-number input mode — PILOT statements are read from the 
Screen Editor, a line number is appended and the resultant 
statement is stored to the program storage area. 

Load mode -- PILOT statements are read from a user specified 
device, otherwise this mode is identical to immediate mode. 

Normally PILOT loads from a file containing only numbered 
statements which are then stored to the program storage area; 
however, un-numbered PILOT statements contained within a 
loading file will be executed as encountered. 

The modes will be discussed in more detail in the paragraphs 
that follow. 

2.1 Command/statement scanning 

PILOT statements are scanned on a strict left to right Y .is 
using a context independent recursive lexical analyzer v uch 
identifies and evaluates all data elements and operators. PILOT 
statements undergo a double scan process: first a syntax scan 
which rejects all syntactically incorrect statements and then an 
execute scan. Even immediate mode commands are double scanned to 
minimize the occurrence of unwanted side effects from partially 
executed invalid commands. PILOT statements in the program 
storage area are syntax checked at the time of entry (immediate 
mode, load mode or Auto-number input mode) and then are not 
syntax checked again during run mode, in order to maximize the 
execution speed. 

The same routines are used for both the syntax scan and the 
execute scan with a flag indicating which type of scan is to be 
performed. 

2.2 Immediate mode 

Immediate mode is the default operating mode; when in this mode 
the interpreter reads PILOT commands/statements from the Screen 
Editor and operates upon them. Input lines consists of an 
optional line number and an optional PILOT statement with the 
following rules governing the interpreters actions: 

line # PILOT resultant action 

statement 

YES YES Store line in program storage area, \ 
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YES 

NO 

Delete 1 

NO 

YES 

Execute 

NO 

NO 

No-opera 


2.3 Run mode 

While in run mode, the interpreter executes previously stored 
PILOT statements from the program storage area. Run mode is 
entered by the immediate mode execution of a Run, Jump, Use or 
End command. Run mode is terminated by a run-time error, the 
end of program execution, an operator BREAK or system RESET. 

2.4 Auto-number input mode 

While in auto-number input mode, the interpreter accepts un- 
numbered PILOT statements from the Screen Editor, appends an 
internally generated line number to each statement and stores 
the resultant statement to the program storage area. Syntax 
errors are reported and the offending statement is not stored. 

Auto-number input mode is entered by the immediate mode 
execution of an Auto command and is terminated by the operator 
entry of an empty line. 


2.5 Load mode 

Load mode is identical to immediate mode, with the exception 
that statements are read fr:^ a specified device/file rather 
than from the Screen Editor. Load mode is entered by the 
execution of a Load command £.nd is terminated by an I/O error or 
an end-of-file condition frcm the device/file being read. 


2.6 Graphics mode 


Graphics mode is a screen mode, rather than an operating mode as 
discussed in the preceding paragraphs. The screen is usually in 
one of two modes, text mode or graphics mode. The default mode 
is text mode in which the screen is organized as 24 lines of 40 
characters each. The user may select graphics mode by the 
execution of the Graphics command, in which case the screen is 
reorganized to a graphics screen with a 4 line text window at 
the bottom. 


The current mode and the transitions between modes are carefully 
controlled and monitored by the interpreter because: 

The highest available RAM location changes when going into 
and out of graphics mode, thus requiring a movement of the 
string variable list. 

Different O.S. interfaces and database variables are 
utilized for screen I/O in the two modes. 
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3. Special considerations 

The paragraphs that follow discuss some of the special 
considerations that were made during the design and 
implementation of the Atari PILOT interpreter. 


3.1 Error reporting 

In order to aid the user in the correction of syntax errors, the 
interpreter highlights a character, in the offending statement, 
that is the source of the error or is immediately to the right 
of a field that is incorrectly specified. The fact that the 
highlighting is usually to the right of the error is a 
consequence of the fact that the lexical analyzer never 
backtracks, that data type errors are detected after lexical 
scanning and that syntactical ambiguities may lead to the 
postponement of error detection. 

3.2 BREAK key monitoring 

The BREAK key is supposed to provide a graceful termination of 
any on-going process; accordingly the pilot interpreter monitors 
the BREAK key at the following points: 

Between the scanning of each statement (all modes). 
Periodically during the execution of the Pause command. 
Periodically during the execution of the Tsync command. 
Between the execution of each Graphics sub-command. 

When an operator BREAK is detected, the interpreter stops the 
then current activity and returns to immediate mode execution. 


3.2 Trace mode 

Trace mode is a special mode which may be utilized in 
conjunction with run mode to aid in the debugging of PILOT 
programs. While in trace mode, the interpreter will write to 
the text screen (or window) the PILOT statement about to be 
executed; this is done regardless of whether or not the 
statement condition field evaluates to true or false. 


3.3 Run-time error minimization 

I \ 

Some steps have been taken to minimize the possibilites for 
producing run-time errors in PILOT programs; among the items 
accounted for are: 

All statements are syntax checked before being stored to the 
program storage area. 

Accept buffer and text expression buffer results are 
truncated on overflow, with no error reported. 

The accept buffer and command line input buffer are larger 
than the largest line which may be entered from the Screen 


Ed i tor . 

The graphics screen cursor control includes in-bounds/out- 
bounds tests and line clipping to eliminate "cursor out of 
bounds" errors from the Display Handler. 

No explicit OPEN command is provided, the device/filename 
and the data direction being provided by the READ and WRITE 
commands themselves. 

The string variable list is moved when entering graphics 
mode so that "insufficient memory" error will not occur 
except when there is really not enough memory. 

The Use stack is cleared on immediate mode execution of Run, 
New, program statement insertion, program statement deletion 
and run mode execution of Load, so that the Use stack is 
guaranteed always to be empty or to contain valid return 
addresses . 

String variable operations are allowed on null strings and 
undefined strings and no explicit declaration of string 
length is required (or allowed for that matter). 
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4. Internal data structures 

This section details the internal data structures used by the 
PILOT interpreter. A memory map showing the gross use of RAM is 
provided below: 


+ 


+ 

I 

+ 

I 

+ 


O.S. 


P I LOT 


stack 


O.S. 

data 

base 


+ 

| P I LOT 
I static 
I var iables 
H — 

I system 
I booted 
I software 
+ 

I accept 
j buffer 
+ 


+ 

I 

+ 

I 

+ 

I 

+ 


+ 


+ 


+ 


+ 


0000-007F 
G 080-00FF 
0 1 00-01FF 

0 200-04FF 
0500-06FF 


4 ll 

5e t--K 


I* “H'VvS 

IjL^AtAcClv^V.- 


0700-???? (need not be present) 


(one memory page) 


program 

storage 


+ 




free 

region 


+ 


+ 


string 

storage 


+ + 

I Screen | 

I Editor | ????-end of RAM 

I display | 

| data | 

+ + 


% 


PILOT utilizes the entire second half of memory page zero (0080- 
00FF) for variables, pointers and tables, and in addition, 
utilizes pages 5 and 6 (0500-06FF) for the same. Memory page 1 

contains the 6502 hardware stack and is completely reserved for 
that purpose. 


PILOT starts the 
memory region at 
was booted, that 


program storage 
power-up time, 
address will be 


area at the bottom of the free 
If no disk or cassette software 
0700, otherwise the address 
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will be at the end of the booted software. PILOT starts the 
string storage area at the top of memory just below the display 
list/data region reserved by the Screen Editor. 
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String variables are dynamically assigned from the high address 
region of the free memory space downward. The variables are 
stored in a structure called the string list which is ordered by 
the collation sequence of the variable names contained therein. 
String names and their values are stored using standard ATASCII 
encoding, one character per 8-bit byte. 


4.1.1 String storage 

String variables (strings) ore stored in memory using sequential 
storage, with two pointers demarking the beginning and end of 
the storage area. Pointer S2H [00B4] marks the end of the list 
and does not change (except when entering or exiting graphics 
mode); pointer S2L [00B2] marks the start of the list and 
changes every time an item is inserted or deleted. 


+ + 

| S2L *-+ 
+ + 


+ 

| S2H 
+ 


-- + 
* 1 " 


H — 

>| 1st item I 

+ + 

| 2nd item I 

+ + 


+ 

last item I 
+ 

> (1st byte after 


I 

+ 

I 

+ 


low memory address. 


high memory address, 
last item) 


When the string list is empty, 
first unusable byte at the end 
established from O.S. variable 
and is readjusted whenever the 
due to a Graphics command exec 


S2L and S2H both point 
of memory. The value 
MEMTOP [02E5] at power 
re is a change in the s 
ution . 


to the 
of S2H is 
-up time 
creen mode 


I A 1 AK1 rlijUl ^ l j . i 


Each item in the string list has the format shown below 


7 

+ 

| item size 
+ - 

i 

H ” 

| name size 

_! — 

I name value 


= 1 to 2 54 

| bytes of 

| ATASCII 

H 

I data size 


H — — — — — — — 

| data value 

I 

= 0 to 254 

| bytes of 

| ATASCII 
+ 



The item size is also used as 
a relative pointer to the next 
item in the list. 


1 to 254. 


0 to 254. 


The first item in the list is the variable with 
in the collation sequence, with the rest of the 
ordered accordingly. 


the name lowest 
list being 


4.1.2 String pointers 

When scanning and manipulating strings the interpreter utilizes 
4-byte pointers which contain a 16-bit base address plus 8 
unsigned offsets to the beginning and end of the substring being 

dealt with. 


7 

0 



| base 

H — 

| pointer 

1 

- + 
1 

byte 0 
1 


| start offset 1 

2 


lend offset 
+ 

( + 1) 1 

3 



The pointer to a null substring will have the start offset equal 
to the end offset. 


4.1.3 String variable name and value pointers 

The lexical analyzer returns, as part of its calling sequence, a 
pointer to the name and a pointer to the value of each nam 
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string variable it encounters. The name pointer is returned in 
4-byte pointer variable NP IRBOE) and the value pointer i" 

for the formJt b of e thn 1 ? t h r r VOri - ble Dp I00C2] , see section 4.1.2 
tne rormat of the 4-byte pointer variables. 


4.3.4 String name temporary 

ind?rf^i t0 S01 !! 3 problem arising from the use of string 

•C-$$ABC-°DEFM 6 ba rget for a Compute or Accept command (e.g. 
ivn!? i , ' all target string names are moved to a 

expressio^to located memory region prior to evaluating the text 

extent and is £?? ri ? h *I ° f the ’ = '* This re 9 ion is 257 bytes in 
extent and is allocated upward from the top of the proqram list 

and deaHocated at the end of the command execution? ?f ' 

intero^Jp? memory is available for the allocation, the 
interpreter will produce a run-time error. 


^ t i ^ k i a ^ ^ 


^ L La X L JL l » i Ull 


.1 ,1 - 1\ u v ~ o u; 


4 . 2 Numbers 

All PILOT language numeric data is stored internally in 16-bit, 
two’s complement integer form, with the least significant byte 
(lsb) being at the lower address. Numeric overflow may occur as 
a result of some numeric operations and is not considered an 
error by the interpreter. 


4.2.1 Numeric variables 

The PILOT numeric variables ’#A’ through * # Z * are stored 
sequentially in a statically assigned table which starts at 
location 051B. 


+ 


I # A value | 


I #B value | 


+ 


#C value 


+ 

I 


+ 

I 


I 

+ 


I 

+ 


I f Z value | 


address = 051B. 
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4.2.2 Numeric expression stack 


Numeric expressions are 
which is statically assi 
results to support two 1 
parentheses. The stack 
of the expression #A + ( 
the expression operands 
seen in the statement of 
each operator is the ROM 
is to perform the diadic 
completed, the three wor 
have been replaced with 


evaluated using an expression stack 
gned and has room for the partial 
evels of nested (non-r edundant) 
is shown below prior to final evaluation 
#C / 4); notice that the stack contains 
and operators in the same infix form as 
the expression. The stack entry for 
address of the arithmetic routine which 
operation; when the operation has been 
ds at the then current top of stack will 
the numeric result of the operation. 


+ + 

I ESTKP * + --■ > 

+ + 


+ 

I 

+ 

I 

+ 

I 

+ 

I 

+ 

I 

+ 


+ 

I 

+ 


+ 

#A value | 

+ 

+ oper. | 
+ 

#C value | 
+ 

/ oper. | 

+ 

4 I 

+ 

current I 
top of = 
stack +2 | 

+ 

I 

+ 


bottom of stack addr 


0093. 


The expression stack po 
quantity which contains 
current top of stack (n 
of an empty stack ESTKP 
for every item added to 
item deleted from the s 


inter ESTKP [0093] 
an index value to 
ext available free 
contains 0 and is 
the stack and dec 
tack . 


r 


is a single byte 
the word beyond the 
word) . For the case 

then incremented by 2 
emented by 2 for ever 


y 


4.2 


3 Numeric result value and 


address . 


The lexical 
the integer 
pointer var 
in variable 
POINT [ 00B6 
the integer 
altered. 


analyzer returns, 
value and the addr 
iable it encounters 
NUMBER [ 00B8] and 
]. For special var 
value is returned 


as part of its calling sequence, 
ess of each numeric variable or 
. The integer value is returned 
the •v^lue is returned in variable 
iables (%x) and numeric constants 
in N0MBER, and POINT is not 

address 


4.3 Program storage 


Deferred program statements are stored in memory using 
sequential storage, with two pointers demarking the beginning 
and end of the storage area. Pointer S1L [00AE] marks the start 
of the list and does not change; pointer SlH f 0 0B 0 ] marks the 
end of the list and changes every time an item is inserted or 

deleted . 


H — — *4- 

| S 3 L *- + 
+ + 


H — — — — — — — + 

>| 1st item I low memory address. 

+ + 

| 2nd item I 

+ + 


+ + 

| last item I high memory address. 
+ + 

+ 1 

I slH *- + > (1st byte after last item) 

+ + 


When the program list is empty, S1L and SlH both point to the 
first usable byte at the beginning of the free memory region. 
The value of S1L is established from O.S. variable MEMLO [02E7] 
at power-up time and is not altered thereafter. 

Each item in the program list has the format shown below: 


7 0 

-i h 

| item size I 

+- - + 

I I 

+ + 

I 2 I 

H — — — — — — + 

| line number I 

+ - - + 

I I 

H 1" 

| statement sizel 

-i + 

| statement I 

I I 

= 1 to 254 

| bytes of I 

| ATASCII. I 

+ + 


The item size is also used as 
a relative pointer to the next 
item in the list. 


Contains the binary line 
number in msb/lsb order . 


1 to 254. 


Contains a single PILOT i 

source statement. Got- , 


The first item in the list is the statement with the lowest line 
number, with the rest of the list being ordered accordingly. 

The fact that a program list entry is a special case of a string 


list entry is purely intentional. 


4.4 Use stack 


The return addresses for Use 
which is statically assigned 
Each stack entry is the memo 
the one containing the execu 


commands 
and has 
ry addres 
ted Use c 


are 

ret 

room 

for 

s of 

the 

ommand . 


ined in a 
eight ent 
statement 


stack 
r ies . 
after 


H b 

| USTKP *+ 
+ 1 


+ + 

| return I 
+- addr -+ 

I #1 I 

+ + 

| return I 
+- addr -+ 
I #2 I 
+ + 

I current I 
+- top of -+ 
| stack +2 I 

+ + 

I I 


bottom of stack addr = 050B 



+ 

return I 

addr -+ 

#8 I 

— b 


The Use stack pointer USTKP [0090] is a single byte quantity 
which contains an index value to the word beyond the current 
top of stack (next available free word). For the case of an 
empty stack USTKF contains 0 and is then incremented by 2 for 
every item added to the stack (Use command) and decremented by 2 
for every item deleted from the stack (End command) . 
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4 . 5 Buffers 

The PILOT interpreter contains several text buffers, which are 
each defined and delimited by a cor respoinding 4-byte pointer. 
Each of’ the buffers is described in the paragraphs that follow. 


4.5.1 Command line input pointer/buffer 

The command line input pointer INLN [0080] is a 4 -byte . pointer , 
as described in section 4.1.2, which points to and delimits the 
PILOT command/statement to be executed. When in immediate mo e, 
INLN points to the buffer COMBUF [0676] which is the target for 
a logical line of text from the Screen Editor. The example 
below shows the state of the command line input pointer/buffer 
immediately after the input of 'RUN* from the screen. 


INLN = 0080 COMBUF = 0676-06F0 

■) — — f 

| base *-+ > 

+- - + 

| address I 

+ + 

|startx= 0 I 

+ + 

| endx = 4 I 
+ + 


+ 

I R I 

+ !■ 

I 0 I 

+ + 

I N I 

+ + 

| <EOL> I 

H h 

! I 

+ 

I I 

I I 

H f- 

I I 

+ + 


When PILOT is in run mode, the INLN pointer points 
statements in the program storage area (instead of 
that case the base address points to the beginning 
statement allocation and the start index contains 
which offsets the overhead bytes. See section 4.3 
format of the program statement storage. 


to program 
COMBUF) . In 
of the 
a value of 6 
for the 
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4.5.2 Accept pointer/buffer 


The accept buffer pointer ACLN [0088] is a 4-byte pointer, 
as described in section 4.1.2, which points to and delimits the 
current accept buffer contents. ACLN always points to the 
dynamically assigned accept buffer which resides in the 256 byte 
page at the beginning of the free memory region. The buffer is 
allocated at power-up time and starts at the then current 
address contained in O.S. variable MEMLO [02E7]. The example 
below shows the state of the accept buffer pointer/buffer 
immediately after the execution of the PILOT statement 
' A : =HELLO ' 


ACLN = 0088 

+ + 

I base *-+ 

H — + 

I address | 

H 

|startx= 0 | 

f- 

| endx = 7 I 
+ + 


address assigned at power-up 

+ + 

> I <blank> | 

+ + 

I H | 

+ + 

I E | 

+ + 

I L | 

+ + 

I L | 

H -f 

I o | 

H + 

I <blank> | 

+ + 

I 

I I 

f_ 

I I 

+ + 


KJ oK v 




4.5.3 Text expression evaluation pointer/buffer 

The text expression buffer pointer TELN [008C] is a 4-byte 
pointer, as described in section 4.1.2, which points to and 
delimits the result of the evaluation of a PILOT text 
expression. TELN always points to the buffer TEXBUF [0577]. 

The example below shows the state of the text expression 
evaluation pointer/buffer immediately after the execution of the 
PILOT statements ' C : $NAME=JOE ' and 'T:HI, $NAME\ ' . 


TELN = 008C 


+ + 

| base *- + 
+- - + 

I address | 

+ + 

I star tx= 0 | 

+ + 

I endx = 7 I 
+ + 


TEXBUF = 0577-0675 



+ 

I 

+ 

I 

+ 

I 

+ 

I 

+ 

I 

+ 


H 


I 


<blank> 


J 


0 


E 


+ 


+ 


+ 

I 

+ 

I 

+ 

I 

+ 

I 

+ 

I 

+ 

I 

+ 

I 

+ 


I 

+ 

I 

+ 


Although TEXBUF could in theory be dynamically assigned, there 
is code within the interpreter which accesses the buffer by name 
rather than using the pointer TELN, thus making dynamic 
assignment impossible (without coding changes to the 
interpreter) . 
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4.6 Graphics parameters 


The internal 
variables to 
which relate 


graphics routines use several different types of 
perform the screen graphics computations, most of 
to either line clipping or direction calculations 


4.6.1 X & Y coordinates 


To minimize the effects of accumulating errors when performing 
relative cursor movement (DRAW, GO or FILL), where the cursor 
positions are not general integral, the 
maintained in memory in a 3-byte format 


graphics 
as shown 


coordinates are 
below : 


+ 


I 1 sb 

1 

byte 0 

+ - 

- + 


I msb 

1 

1 

+ ““ 

- + 


| fraction 

J 

1 

2 


Each coordinate contains two bytes of integer and one byte of 
fraction, all in two's complement representation. When data is 
either plotted to the screen, read from the screen or the 
coordinate values accessed using ’%X' and ' %Y ' , the most 
significant bit of each fraction is used to round the integer 
values of the coordin: : :s (working values only, not the 

reference value) . 

The coordinate reference values are contained in variables GX 
[ 0 0EC ] and GY [00EF]; other working variables also utilize this 

format as shown below: 


Name 


Function 


GX 

Current curso 

GY 

Current curso 

GXNEW 

Cursor target 

GYNEW 

Cursor target 

GX1 

Line clipping 

GY1 

Line clipping 

GX2 

Line clipping 

GY2 

Line clipping 


x-coord ina te . 
y-coord inate . 
position x-coord i nate . 
position y-coord i nate . 


line 

end 

point 

1, 

x-coord 

line 

end 

point 

1, 

y-coord 

1 ine 

end 

point 

2, 

x-coord 

1 ine 

end 

point 

2, 

y-coord 


4.6.2 Theta angle 

The graphics theta 
THETA [00F2] as an 
graphics variable 


angle is maintained internally in variable 
integer value that ranges from 0 to 359. The 
%A ' returns this value directly. 
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4.6.3 Pen color 

The currently selected pen color is retained in single byte 
variable PEN [0553] which may have the following values: 

0 = ERASE. 

1 = RED. 

2 = YELLOW. 

3 = BLUE. 

4 = UP. 


a 

4.6.4 Computation# - variables 


The following variables are used during the computation of line 
end points by the clipping algorithm: 


DELX [00CA] Integer delta x (line slope). 

DELY [00CC] Integer delta y (line slope). 


GACC [ 0 0CE] 

GTEMP [ 0 0D2 ] 
GTEMP2 [ 00D6 ] 


4 byte integer accumulator. 
4 byte integer temporary. 

4 byte integer temporary. 


\ 
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4.7 Sounds 


The sound parameters 
statically allocated 


for the Sound command are retained 
table as shown below: 


i n a 




| entry #4 I 



| entry #3 I 

+ + 

| entry #2 ! 

+ 

| entry #1 I 
+ + 


low memory address — 0555. 


Each table entry is a 
formats shown below: 


2-byte quantity with one of the two 


7 0 

| memory lo I Byte 0 

+-+ . 
1 0 1 address hi I J 


or 

7 0 

+-+-+-+-+-+-+-+-+ 

| (unused) I Byte 0 

1 1 | x x I constant I 1 


An entry of 
table unless 
high memory 
or physical 


all zeros is used to flag the curr 
the table is full. The table is 
address to the low memory address 
end of table is reached. 


ent end of the 
scanned from the 
until the logical 


The data value ^ n t he i s d truncated C to 1 a d 5-bit h quantity which is 
the n S used^as°a S table Index to obtain one of the 32 -lues shown 
the tablecSH^ The value obtained from the table is sent 
to one of the hardware audio registers to generate 

tone . 
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Numeric 

Audio 

value 

r eg i ster 

Pi 

0 

1 

243 

2 

2 30 

3 

217 

4 

204 

5 

193 

6 

182 

7 

172 

6 

162 

9 

153 

10 

144 

11 

136 

12 

1 28 

13 

121 

14 

114 

15 

108 

16 

102 

17 

96 

18 

91 

19 

85 

20 

81 

21 

76 

22 

72 

23 

68 

24 

64 

25 

60 

26 

57 

27 

53 

28 

50 

29 

47 

30 

45 

31 

42 


Note 

Fr eq . 
(desired) 

rest 

0.0 

C 

1 30.81 

c# 

1 38. 59 

D 

146.83 

D# 

155. 56 

E 

164.81 

F 

174.61 

F# 

185. 00 

G 

196.00 

G# 

207. 65 

A 

220.00 

A# 

233.08 

B 

246.94 

C 

261.63 

C# 

277.18 

D 

293.66 

D# 

311.13 

E 

329.63 

F 

349. 23 

F# 

369.99 

G 

392.00 

G# 

415. 30 

A . 

440.00 

A# 

466.1 6 

B 

493.88 

C 

523. 25 

c# 

554. 37 

D 

587. 33 

D# 

622. 25 

E 

659.26 

F 

698.46 

F# 

739.99 


Fr eq. 

Er r or 

(actual ) 

(%) 

31960.50 

— 

130. 99 

+ 0.14 

1 38. 36 

-0.17 

146. 61 

-0.1 5 

155. 90 

+ 0.22 

164.74 

-0.04 

174.65 

+ 0.02 

1 84.74 

-0.14 

196.08 

+ 0.04 

207.54 

-0.05 

220.42 

+ 0.19 

233. 29 

+ 0.09 

247.76 

+ 0.33 

261.97 

+ 0.13 

277.92 

+ 0.27 

293. 22 

-0.15 

310. 30 

-0.27 

329.49 

-0.04 

347.40 

-0. 52 

371.63 

+ 0.44 

389.76 

-0.57 

415. 07 

-0.06 

437.82 

-0.50 

463. 20 

-0.63 

491.70 

-0.44 

523. 94 

+ 0.13 

551.04 

-0.60 

r i.86 

+ 0.77 

"'26. 68 

+ 0.71 

565.84 

+ 1 . 00 

194.79 

-0.53 

743.27 

+ 0.44 


The formula for converting audio register values to frequency 
i s : 


frequency = 63921 / (2 * (audio register value + 1 )) 


4 
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^.8 Command/reserved word tables 


All cc.Tijnand name, numeric and 
word recognition is performed 
contained in the cartridge ROM 
table is shown below: 


relation operator, and reserved 
using a single segmented table 
(CTAB) . The format for that 


+ 

I I 

I PILOT I 

I commands | 

I I 

+ 


numeric/ | 
I relation | 
I operatorsl 

I I 

+ + 

I I 

I graphics | 

I sub-comm | 

I I 

-|- + 

I I 

I pen | 

I colors j 

I I 

+ 

I I 

I 'ON ' / 'OFF * | 

I I 

+ -f 


Each segment in the table contains 
a segment terminator byte of zero, 
below : 


one or more name entries plus 
A single name entry is shown 


7 0 

+ — t--t — + 

101 | 

+ -+ -+ 

1 0 1 exact | 

= name in = 

I 0 I ASCII \ | 

+ -+ - + 

101 | 

+ - + - + - + -H 1 | 

I I I value | 

+ -H 1 I I--H (-- + - + 


In some cases the 7-bit value associated 
sufficient, for example the graphics pen 

other cases the 7-bit value is used as an ind< 
bit values (CDTAB) . 


wi tn 
color 


name is 
ef initions 
to a table 


In 

of 16- 
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5. Procedure modules 

This section provides module descriptions for the major 
subsystems that were used to implement the Atari PILOT 
i nterpreter . 


5.1 Memory management package 

This package contains the routines listed below, all having 
functions relating to the management of memory resources: 

MALLOC -- Memory allocate. 

MDEALL -- Memory deallocate. 

MOVIA -- Move memory block using increasing addresses. 

MOVDA -- Move memory block using decreasing addresses. 

This memory management scheme utilizes two separate allocation 
regions; one region starting in low address memory and working 
upward, and the other region starting in high address memory 
and working downward. In PILOT, one region is used for program 
storage and the other region for string variable storage. The 
regions are initially defined by four pointers: 

S1L = Pointer to start (bottom) of region 1 (lower region). 

S3H = Pointer to end (top) of region 1. 

S2L = Pointer to end (bottom) of region 2 (upper region). 

S2H = Pointer to start (top) of region 2. 

S1L and S2H define the extent of managed memory er. ' are not 
altered by the management routines. S1H and S2L s“e initially 
equal to S1L and S2H (respectively) indicating nu .1 allocations, 
and thereafter always point to the next available unused memory 
location. Allocation of memory is accomplished by creating a 
"hole" in the desired region (by moving memory if necessary) ; 
and deallocation of memory is accomplished by eliminating a 
"hole" in the region. An allocated block of memory always 
contains its own size as the first (lowest address) two bytes of 
the block; this is the only memory overhead associated with 
management. Note, however, that the block size also forms a 
relative pointer to the next allocation block which can be 
useful to the application if the blocks within a region form a 
sequential list. 

The user always specifies the address at which allocation is to 
start; this address may be inside the region ("between" already 
allocated blocks) or may be the next available address just 
outside the region. The user specifies the address of the block 
to deallocate also, the size is assumed to still be in the first 
two bytes of the block. 

The section that follows summarizes the calling sequences of the 
current routines: 

MALLOC -- Memory allocate routine 

Calling sequence: 

’MEMA’ contains the address at which the allocation is to occur. 
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' MEMB ' 


This address is either 
the region (content of 
already allocated block 


the next available 
51H or S2L) or the 
within the region. 


address 

address 


outside 
of an 


contains the number of bytes 
two overhead bytes. 


to allocate. 


including the 


JSR 

BNE 


M ALLOC 

not enough memory to satisfy allocation 


'MEMA' 


contains the lowest address 


in the allocated block. 


The first (lowest) 
number of bytes in 


two bytes of the allocated block contain the 
the block. 


MDEALL -- Memory deallocate routine 
Calling sequence: 


'MEMA' 

JSR 


contains 

(lowest) 


the address of the block to deallocate. The first 
two bytes of the block must contain the block size. 


MDEALL 


'MEMA' 


contains the address of the 
the deallocated block after 


block following (higher address) 
the deallocate. 


MOVDA and MOVIA are u 
purpose block move ut 
obtained from the sou 


-d by MALLOC and 
iities and their 
ce file. 


MDEALL; they are general 
calling sequences may be 


5.2 String handling package 


This package contains the routines listed below, all having 
functions relating to the handling of named strings of variable 
1 ength . 


SFIND -- Find named string in 
SDELET -- Delete named string 
SINSRT -- Insert named string 
SMATCH -- Find substring in s 
SCOMP -- Compare two strings 

This package utilizes the memor 
section 5.1 and deals with two 
where one list is the program 1 
variable list. 


list. 

from list (if it exists), 
into list (by name order), 
tring, if present, 
for collation. 

y management package described in 
separate lists of named strings, 
ist and the other is the string 


In order to understand the calling sequences, a few definitions 
must be given first: 

Text data — any contiguous grouping of one or more bytes which 
are to be treated as a unit. The word 'JACK', when stored in 
memory as shown below, is an example of text data. 

+ + + + + 

|'J' |'A' I'C' | 'K* I 

+ + + + + 


String -- text data to which a string length byte has been 
appended, as shown below. 

+ + + + + + 

I 4 I ' J ' | ' A * | 'C ' | 'K ' | 

+ + + + + + 


Text pointer -- a four byte element consisting of a base memory 
address and two indices (a starting and an ending index). The 
text pointer explicitly delimits a (possibly null) group of 
bytes starting with the byte at address BASE ADDRESS + START 
INDEX and ending with the byte at address BASE ADDRESS + END 
INDEX - 1. By convention, if the start index equals the end 
index, the text data is considered to be null. See also section 
4.1.2. 


Named string — a string which can be referenced by a symbolic 
name consisting of text data; a named string is often known as a 
string variable. The name and data portions may each be up to 
254 bytes in length. See section 4.1.1 for the storage format 
for named strings. 


Parameter area -- a portion of page zero memory which contains 
text pointers which have assigned meanings for each of the 
string operations provided by this package. These parameters 
are initially setup by the user and provide the parameter 
passing mechanism for all operations. 
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NP (name pointer) -- when used, this delimits a 
string name. 

DP (data pointer) -- this delimits string data; often 
associated with the named string specified by NP. 

MP (pattern match pointer) -- when used, this 

delimits comparison or pattern matching data to be 
used in conjunction with DP. 

LP (list pointer) -- points to the string list to be 
accessed . 

The section that follows summarizes the calling sequences of the 
routines: 


SFIND -- Find named string in list. 


Function: SFIND scans a list of named strings, attempting to find 
the name delimited by the NP text pointer. If the named string 
is found, DP will point to the string data. 

Calling sequence: 


LP = address of start of list of named strings. 

NP = text pointer delimiting a string name. 

JSR SFIND 

BNE name null or named string not found 

DP = text pointer to string data portion, if found, 
address points to string byte count (n) , start 
= 1 and end index = n+1 (assuming non-null data 
both indices = 1 ) . 


Base 
index 
, else 


SDELET -- Delete named string, if found. 

Function: Finds the named string, if it exists, removes the named 
string from the list and deallocates the memory utilized by 
that string. 

Calling sequence: 

LP = address of start of string list to access. 

NP = text pointer delimiting a string name. 

JSR SDELET 

BNE name null or named string not found 


SINSRT -- Insert named string to list. 

Function: Deletes a prior occurrence of the named string, if found, 
and then inserts the new named string into the list. The 
string is placed in the list so that the names are in 
standard collation order. 


Calling sequence: 


\ 1 J. i ) i \ X 


i- J juw x 


U 1 UV^ i 1 X l J X XWl.'t 


i.* W V 


U U / 


LP = address of start of string list to access. 
NP = text pointer to string name. 

DP = text pointer to string data. 

JSR SINSRT 

BNE no room in memory for insertion 


SMATCH -- Find substring in string if present. 

Function: examine string for first occurrence of substring. 
Calling sequence: 

DP = text pointer to source text data. 

MP = text pointer to match text data. 

JSR SMATCH 

BNE match text not in source text 

SP = text pointer to first occurrence of match data in source. 


SCOMP -- Compare two string for collation order. 

Function: compares two strings to determine their collation order. 

Calling sequence: 

DP = text pointer to text data. 

MP = text pointer to text data. 

JSR SCOMP 

BEQ DP text data = MP text data 

BCS DP text data >= MP text data 

BCC DP text data < MP text data 

Note : The comparison is based upon the numerical encoding of 
the characters involved; moreover, when one text data is a sub- 
set of the other text-data, the shorter one is considered to be 
lower (<) in the collation sequence. 


Routines IFIND, ICOMP, IMATCH, SEND, ILENG, PSETUP, PMOVE, SMOVI 
a id SNXTI are lower level routines used to implement the ones 
described above. Their calling sequences may be found in the 
source listing. 
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5.3 Integer arithmetic package 


Double Precision Integer 


(Signed) Arithmetic Package (DXXXIY) 


This package contains 
functions relating to 
(except as noted) : 


the routines listed below, all having 
two-byte signed integer arithmetic 


Funct ion 


Routine (s) 


Addition 
Subtraction 
Multiplication 
Division/ modulus 
Compar i son 
Negation 
Relational tests 
Number to ASCII 
ASCII to number 
Move number 


DADDI , 

DADDS, 

DADDA 

DSUBI , 
DMULI 

DStJBA 


DDIVI , 

DMODI 


DSCMI , 
DNEGI 

DCMPI , 

DCWC I , 

DEQTI , 
DECASC 
ASCDEC 

DNETI , 

DGTTI , 

DMO VI , 

DLOADA , 

DSTORA 


DCMPA 

DGETI , DLTTI, DLETI 


These routines have a common calling convention and data base. 
Ail data is assumed to be two bytes in length (low byte 
followed by high byte), and all data is referenced by its 
position reiative to the symbol 1 DTAB ' . The sample program 
that follows will hopefully make this clear. 


; DATA REGION 

* = $B0 

DTAB=* 

/ 

VA *=*+2 

VB *=*+2 

VC *=*+2 

i 

; PROGRAM REGION 


; ORIGIN OF DATA REGION. 

; START OF DOUBLE PRECISION DATA. 

; DECLARE ' VA ' . 

; DECLARE ' VB ' . 

; DECLARE 'VC'. 


* = $B000 


COMPUTE VC = 

(VC + VA) 

LDX 

# VC-DTAB 

LDY 

# VA-DTAB 

JSR 

DADDI 

LDY 

IVB-DTAB 

JSR 

DMULI 

JSR 

DMULI 

LDA 

#-2 

JSR 

DADDS 


; ORIGIN OF PROGRAM REGION. 
(VB ** 2) - 2. 


; VC = (VC + VA) ... 


; ... * (VB ** 2) . . . 



The double precision subroutines do not, in general, alter the X 
an registers; and since the X register always specifies the 
estinat ion of the result, great savings in code can be achieved 
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when computing expressions with several terms by not including 
the redundant LDXs and LDYs . 

The section that follows summarizes the calling sequences of the 
resident routines. 

Name Function 


DADD I 

DADDS 

DADDA 

DSUBI 

DSU3A 

DMULI 

DDIVI 

DMODI 

DNEGI 

DMOVI 

DLOADA 

DSTORA 


DTAB (X) 
DTAB(X) 
'ACC' = 
DTAB (X) 
'ACC' * 
DTAB (X) 
DTAB (X) 
DTAB (X) 
DTAB (X) 
DTAB ( X ) 
'ACC 1 = 
DTAB (X) 


= DTAB ( X ) + DTAB (Y) 

= DTAB (X) +/- A 
’ACC’ + DTAB (Y) 

= DTAB (X) - DTAB(Y) 

'ACC' - DTAB(Y) 

= DTAB ( X ) * DTAB(Y) 

= DTAB (X) / DTAB(Y) 

= ABS (DTAB (X) ) MOD ABS (DTAB ( Y ) ) 
= - DTAB (X ) 

= DTAB (Y) 

DTAB(Y) 

= 'ACC' 


DSCMI 

CC = DTAB (X) 

• 

• 

DTAB ( Y) 

(SIGNED) 

DCMPI 

CC = DTAB ( X ) 

• 

• 

DTAB(Y) 

(UNSIGNED) 

DCWCI 

CC = DTAB (X) 

• 

* 

A , Y 

(UNSIGNED) 

DCMPA 

cc = 'ACC' : 

DTAB ( Y ) 

(UNSIGNED) 

DEQTI 

DTAB (X) 

= 1 

IF 

DTAB ( X ) 

= DTAB(Y) , ELSE 0. 

DNETI 

DTAB ( X ) 

= 1 

IF 

DTAB (X) 

<> DTAB (Y) , ELSE 0. 

DGTTI 

DTAB ( X ) 

= 1 

IF 

DTAB ( X ) 

> DTAB(Y) , ELSE 0. 

DGETI 

DTAB ( X ) 

= 1 

IF 

DTAB (X) 

>= DTAB ( Y) , ELSE 0. 

DLTTI 

DTAB (X) 

= 1 

IF 

DTAB (X) 

< DTAB ( Y) , ELSE 0. 

DLETI 

DTAB (X) 

= 1 

IF 

DTAB (X ) 

<= DTAB ( Y) , ELSE 0. 


Where: 'ACC' is a 'DTAB' variable. 

'cc' refers to 6502 status register bits Z & C. 
is the comparison operator. 


\ 
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5.4 Graphics package 


This package contains the routines listed below, all having 
functions related to generating memory map graphics using the 
system Display handler (S : ) . 


GMOVE 

INTEST 

MOD360 

SETCUR 

SINVAL 

TMULT 

TADDI 

QMULT 

QDI V 

QNEGA 


Plot point or draw/fill line (with screen clipping) 
Test x , y point for being inside the screen limits. 
THETA = THETA modulo 360. 

Convert coordinate systems and set system cursor. 
Calculate SINE (THETA) . 

Triple precision signed multiply. 

Triple precision signed addition. 

Quadruple precision signed multiply. 

Quadruple precision signed divide. 

Quadruple precision negate. 


Other routines exist in this package, but they are oriented 
directly to the syntax of PILOT graphics sub-commands; 

specifically, there are routines to process the following 
sub-commands : 


DRAWTO x,y 
DRAW n 
GOTO x ,y 
GO n 

FILLTO x,y 
FILL n 
TURNTO 0 
TURN 0 
CLEAR 
PEN c 
QUIT 


The most interesting of the routines is GMOVE which contains a 
screen clipping algorithm which allows lines to be drawn 
anywhere within a 65535 by 65535 graphics address space, 
displaying the line segments which pass through the 160 by 96 
visible screen. The algorithm implemented is described in 
section 5-1 of PRINCIPLES OF INTERACTIVE COMPUTER GRAPHICS, 
Second Edition. 


y M X L \ i\ J. 


i. X XJ X 
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5.5 Statement scanning utilities 

The statement scanning utilites aid in the scanning of PILOT 
statements. In general, most of these routines expect a singl 
character in the A register or expect the Y register to index 
into the line pointed to by INLN. The table below lists the 
primary utilities and summarizes their calling sequences. 

Name Function 


CNUMBR Check A = numeric character. 

Clear carry if A = '0' - '9 1 . 

CLETTR Check A = alphabetic character. 

Clear carry if A = 'A' - ' Z * . 

CKEOA Check A = end of atom (non-alphanumer ic character). 

Set cc non-zero if A = ’ 0 * — * 9 ' or 'A' - 'Z'. 

CHKEQS Check A = equal sign. 

Set cc zero if A = '='. 

CHKSEP Check A = comma or space. 

Set cc zero if A = or ’ '. 

CHKTRM Check A = statement terminator. 

Set cc zero if A = <EOL> or '['• 

SCNEOA Scan to end of atom (non-alphanumer ic character) . 

Y = index for pointer INLN. 

SCNLBL Scan to end of label, if present. 

Y = index for pointer INLN. 

SLB Skip over leading blanks. 

Y = index for pointer INLN. 

SKPSEP Skip over separators. 

Y = index for pointer IN-.N. „ 

SCNEOL Scan to end of line. 

Y = index for pointer INLN. 


PyTo M 
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